~ chicken-core (chicken-5) /manual/Module (chicken tcp)
Trap1[[tags: manual]]2[[toc:]]34== Module (chicken tcp)56This module provides basic facilities for communicating over TCP7sockets.89All errors related to failing network operations will raise a condition10of kind {{(exn i/o net)}}.111213=== tcp-listen1415<procedure>(tcp-listen TCPPORT [BACKLOG [HOST]])</procedure>1617Creates and returns a TCP listener object that listens for connections on {{TCPPORT}}, which18should be an exact integer. {{BACKLOG}} specifies the number of maximally pending19connections (and defaults to 100). If the optional argument {{HOST}} is given and not20{{#f}}, then only incoming connections for the given host (or IP) are accepted.212223=== tcp-listener?2425<procedure>(tcp-listener? X)</procedure>2627Returns {{#t}} if {{X}} is a TCP listener object, or {{#f}} otherwise.282930=== tcp-close3132<procedure>(tcp-close LISTENER)</procedure>3334Reclaims any resources associated with {{LISTENER}}.353637=== tcp-accept3839<procedure>(tcp-accept LISTENER)</procedure>4041Waits until a connection is established on the port on which42{{LISTENER}} is listening and returns two values: an input- and43output-port that can be used to communicate with the remote44process. The current value of {{tcp-accept-timeout}} is used to45determine the maximal number of milliseconds (if any) to wait46until a connection is established. When a client connects any47read- and write-operations on the returned ports will use the48current values (at the time of the connection) of {{tcp-read-timeout}}49and {{tcp-write-timeout}}, respectively, to determine the maximal50number of milliseconds to wait for input/output before a timeout51error is signalled.5253Note: this operation and any I/O on the ports returned will not block54other running threads.555657=== tcp-accept-ready?5859<procedure>(tcp-accept-ready? LISTENER)</procedure>6061Returns {{#t}} if there are any connections pending on {{LISTENER}}, or {{#f}}62otherwise.636465=== tcp-listener-port6667<procedure>(tcp-listener-port LISTENER)</procedure>6869Returns the port number assigned to {{LISTENER}} (If you pass {{0}} to {{tcp-listen}},70then the system will choose a port-number for you).7172=== tcp-listener-fileno7374<procedure>(tcp-listener-fileno LISTENER)</procedure>7576Returns the file-descriptor associated with {{LISTENER}}.777879=== tcp-connect8081<procedure>(tcp-connect HOSTNAME [TCPPORT])</procedure>8283Establishes a client-side TCP connection to the machine with the name84{{HOSTNAME}} (a string) at {{TCPPORT}} (an exact integer) and returns85two values: an input- and output-port for communicating with the86remote process. The current value of {{tcp-connect-timeout}} is used87to determine the maximal number of milliseconds (if any) to wait until88the connection is established. When the connection takes place any89read- and write-operations on the returned ports will use the current90values (at the time of the call to {{tcp-connect}}) of {{tcp-read-timeout}} and91{{tcp-write-timeout}}, respectively, to determine the maximal number92of milliseconds to wait for input/output before a timeout error is93signalled.9495If the {{TCPPORT}} is omitted, the port is parsed from the {{HOSTNAME}} string. The format expected is {{HOSTNAME:PORT}}. The {{PORT}} can either be a string representation of an integer or a service name which is translated to an integer using the POSIX function [[http://www.opengroup.org/onlinepubs/009695399/functions/getservbyname.html|{{getservbyname}}]].9697Note: any I/O on the ports returned will not block other running threads.9899100=== tcp-addresses101102<procedure>(tcp-addresses PORT)</procedure>103104Returns two values for the input- or output-port {{PORT}} (which should be a port returned105by either {{tcp-accept}} or {{tcp-connect}}): the IP address of the local and the remote106machine that are connected over the socket associated with {{PORT}}. The returned addresses107are strings in {{XXX.XXX.XXX.XXX}} notation.108109110=== tcp-port-numbers111112<procedure>(tcp-port-numbers PORT)</procedure>113114Returns two values for the input- or output-port {{PORT}} (which should be a port returned115by either {{tcp-accept}} or {{tcp-connect}}): the TCP port numbers of the local and the remote116machine that are connected over the socket associated with {{PORT}}.117118119=== tcp-abandon-port120121<procedure>(tcp-abandon-port PORT)</procedure>122123Marks the socket port {{PORT}} as abandoned. This is mainly useful to close down a port124without breaking the connection.125126127=== tcp-buffer-size128129<parameter>tcp-buffer-size</parameter>130131Sets the size of the output buffer. By default no output-buffering for132TCP output is done, but to improve performance by minimizing the133number of TCP packets, buffering may be turned on by setting this134parameter to an exact integer greater zero. A buffer size of zero or {{#f}}135turns buffering off. The setting of this parameter takes effect at the time136when the I/O ports for a particular socket are created, i.e. when {{tcp-connect}}137or {{tcp-accept}} is called.138139Note that since output is not immediately written to the associated socket, you140may need to call {{flush-output}}, once you want the output to be transmitted.141Closing the output port will flush automatically.142143=== tcp-read-timeout144145<parameter>tcp-read-timeout</parameter>146147Determines the timeout for TCP read operations in milliseconds. A timeout of148{{#f}} disables timeout checking. The default read timeout is 60000, i.e.1491 minute.150If timeout occurs while reading, a condition object of kinds {{(exn i/o net timeout)}}151is thrown.152153=== tcp-write-timeout154155<parameter>tcp-write-timeout</parameter>156157Determines the timeout for TCP write operations in milliseconds. A timeout of158{{#f}} disables timeout checking. The default write timeout is 60000, i.e.1591 minute.160If timeout occurs while writing, a condition object of kinds {{(exn i/o net timeout)}}161is thrown.162163=== tcp-connect-timeout164165<parameter>tcp-connect-timeout</parameter>166167Determines the timeout for {{tcp-connect}} operations in milliseconds. A timeout of168{{#f}} disables timeout checking and is the default.169If timeout occurs while trying to connect, a condition object of kinds {{(exn i/o net timeout)}}170is thrown.171172173=== tcp-accept-timeout174175<parameter>tcp-accept-timeout</parameter>176177Determines the timeout for {{tcp-accept}} operations in milliseconds. A timeout of178{{#f}} disables timeout checking and is the default.179If timeout occurs while waiting for connections, a condition object of kinds {{(exn i/o net timeout)}}180is thrown.181182183=== Example184185A very simple example follows. Say we have the two files {{client.scm}}186and {{server.scm}}:187188<enscript highlight=scheme>189; client.scm190(import (chicken io) (chicken tcp))191(define-values (i o) (tcp-connect "localhost" 4242))192(write-line "Good Bye!" o)193(print (read-line i))194</enscript>195196<enscript highlight=scheme>197; server.scm198(import (chicken io) (chicken tcp))199(define l (tcp-listen 4242))200(define-values (i o) (tcp-accept l))201(write-line "Hello!" o)202(print (read-line i))203(close-input-port i)204(close-output-port o)205</enscript>206207 % csc server.scm208 % csc client.scm209 % ./server &210 % ./client211 Good Bye!212 Hello!213214---215Previous: [[Module (chicken syntax)]]216217Next: [[Module (chicken time)]]